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Display Troubleshooting 


I have no display 


If you know Batocera is booting (the network share is available, you can SSH in, you hear some music, 
etc.) but you have no display, it could be that Batocera is using a different display than intended. The 
simple solution to this is to unplug and replug the display, Batocera should automatically switch over 
to the newest display that was plugged in (sometimes, a laptop that is plugged in to its external port 
will “connect” that first before connecting its internal display, causing the internal display to be 
connected “last”). 


If that still isn't working, try SSH'ing in and run the following: 


export DISPLAY=:0.0 
batocera-resolution listOutputs 
batocera-resolution setOutput <your intended output here> 


If that still isn't working, then it's recommended to skip straight to the advanced display debugging. 
I see the Batocera splash screen, but then it turns black/no input 


It is possible that the official graphics drivers have not been automatically detected and used, and the 
fallback open-source alternative driver is not able to provide the display output (typical if on 
“bleeding-edge” hardware released in the last year). If that's the case, they can be manually 
activated by editing the batocera-boot.conf file. 


If the correct drivers are being used and it's still not working, it's possible that the prime switcher also 
needs to be toggled (common on modern laptops connected to external displays). In case Batocera 
hasn't been able to automatically detect this for you, you can manually activate the prime switching 
by editing the batocera-boot.conf file. 


It can also be the case of a dead USB flash disk. The USB flash drive isn't “dead enough” to prevent 
from booting, but some there are missing parts in the boot sequence and it just hangs at some point, 
and we've seen this happening after the splash screen. In doubt, try with another USB flash drive. 


If using a HP EliteDesk specifically, it may require certain BIOS settings or else the GPU might be 
disabled by the motherboard. 


As a general rule, when you face a black screen during the boot sequence, it can be helpful to enable 
verbose boot mode for troubleshooting. 


The edges of my screen are cut off! 


Most modern TVs come with some sort of setting that slightly zooms in the image. This is normally 
done to prevent garbage pixels from displaying in broadcasts (remnant of a bygone era). Normally, 
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the TV is meant to turn this off when using an input device like a PlayStation or a computer, but 
sometimes it fails to recognize this and keeps it on. Usually you can turn it off manually in that case. 


This setting does not have a consistent name between manufacturers. Names to look out for while 
scouring through your option menus: “Just scan”, “Pixel ratio”, “Zoom”, “Aspect”, “Overscan”, etc. 
These may be in either your per-channel settings or your system settings. 


My screen keeps blinking 


It could be that the TV reports as supporting a refresh rate it isn't actually tuned for, occasionally 
slipping outside of the expected range (which cuts off the signal momentarily). In this case, try 
different “similar” refresh rates, eg. if on a 60Hz display try 59.98Hz. For PCs, first try testing the 
different resolutions as specified in the xrandr section below, then save it to apply on boot. 


If on a device that uses the DRM service specifically (such as Android TV boxes and other SBCs), as 
weird as this sounds try booting back into the eMMC Android firmware and set the resolution to the 
“closest to native” as you can get for that box. For instance, if the box was to support 4K displays, set 
the resolution to 2160p in Android (this is irrelevant of what resolution you want to use for Batocera 
itself). When you reboot back into Batocera, the flashing screen problem may be solved. 


Emulation with 4K and ultrawide monitors, or problems 
when your screen is not fully displayed 


Older 8-bit and 16bit systems, or arcade systems from the 80s and 90s were using 4:3 CRT screens. 
Modern displays are now 16:9 or wider, and can go up to AK, i.e. 2160 pixels high (compared to 480 
or 546 at the time!). 


Having so many pixels to render on the screen is impactful on the system performance. When you 
have a 4K screen or an ultra-wide screen, Batocera will limit the resolution by default to HD 
1920x1080. It's more than enough to render emulators, even the most recent ones. However, when 
you have an ultra-wide monitor, the display may be stretched. 


For 4K monitors, because the resolution is by default resized to 1920x1080, you might see a screen 


that looks like this one (actually it's what 1:1 pixel scaled 1920x1080 is, centered in a 3840x2160 
screen): 
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First, check your TV's scaling settings to ensure that it is currently set to “Stretch”, “Full screen”, 
“Expand”, “Fill” or some terminology similar to that. 


If you've checked for that and the image is still tiny, the best solution is to manually set the resolution 
to “1920x1080” (or “MAXIMUM 1920x1080”) in MAIN MENU > GAMES SETTINGS > VIDEO MODE 
(you can instead do that on a system-by-system basis in the PER SYSTEM ADVANCED 
CONFIGURATION screen). 


VIDEO MODE 


Another use case is when you have a 1280x720 TV, for example, and you want to use bezels that are 
designed for 1920x1080. Batocera can automatically resize the bezels, but sometimes you need to 
force the VIDEO MODE to take your 1280x720 resolution. 


If you absolutely want to use the 4K resolution for whatever reason (shaders looking better, you have 
a non-standard wide format on your TV/monitor...), set the VIDEO MODE to “3840x2160” (turn on 
the STRETCH BEZEL option to force the use of bezels designed for 1920x1080 on your 4K 
resolution, stretching bezels is not available in Batocera 5.27 and lower). As above, this is something 
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you can do on a system-by-system basis instead. 


A Setting the resolution to force 4K has an impact on the emulation performance. 


Everything is appearing too small in the file manager! 


If you use Batocera with a display that provides a high resolution like a 4K monitor, you might have 
trouble reading the text on the file manager ([F1] on the system list on PC) or the configuration 
screens of a few emulators. You can change the default DPI settings by editing batocera. conf and 
look for the section: 


## DPI 

## Workaround when correct DPI setting is not detected 
## if fonts are too small, uncomment next line 

#g Lobal .dpi=96 


When EmulationStation feels sluggish on a 4K TV 


ey This shouldn't be necessary for most TVs that provide a proper EDID packet, but is here 
for those specific situations where they don't. 


There are some SBC + TV combinations where EmulationStation feels sluggish (default theme seems 
to be lagging behind, with a refresh rate like 10 FPS). It's really depending on your own configuration, 
but we have reproduced this with a Raspberry Pi 4 and a couple 4K TV models. By default, ES should 
negotiate with your TV to fix its resolution to 1080p, but sometimes your TV brand doesn't accept it 
and stays at 4K/2160p resolution. You can force a particular resolution by editing it into 
/boot/batocera-boot.conf. 


Force 1080p as the maximum resolution despite what the EDID may report 


In Batocera v31 and higher, the max- 1920x1080 resolution is now an option available to select 
within the standard es. resolution key in /boot/batocera-boot.conf. To force a maximum 
resolution of 1920x1080, open the batocera-boot.conf file and add/alter the following line: 
es.resolution=max - 1920x1080 


You can also force a maximum resolution of 640x480 instead for really slow devices: 


es.resolution=max -640x480 
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For earlier versions of Batocera (v29 and v30), this option cannot be selected in 
es.resolution (it will be ignored). Instead, you must use a different key in batocera- 
boot.conf: 


system.es.maxresolution=1920x1080 


After this, Batocera will take the most suitable refresh rate for the maximum resolution specified and 
use that. 


Force any specific supported resolution in ES instead of the default maximum 
one 


You can get the list of all supported resolution modes by running the following commands via SSH: 


export DISPLAY=:0.0 
batocera-resolution listModes 


For example: 


[root@BATOCERA /userdata/system]# export DISPLAY=:0.0 
[root@BATOCERA /userdata/system]# batocera-resolution listModes 
ax-1920x1080:maximum 1920x1080 
ax—640x480:maximum 640x480 
720x480.59.94:720x480 59.94 Hz 
-59.94:4696x2168 59.94 
.50.00:4096x2160 50.00 
.24.00:4096x2160 24.00 
.23.98:4096x2160 23.98 
.59.94:3840x2160 59.94 
.50.00:3840x2160 50.00 
.29.97:3840x2160 29.97 
.25.00:3840x2160 25.00 
.23.98:3840x2160 23.98 
.60.00:1920x1080 66.86 
.59.94:1920x1080 59.94 
.50.00:1920x1080 50.090 
.29.97:1920x1080 29.97 
.23.98:1920x1080 23.98 
.-59.94:1280x720 59.94 Hz 
.50.00:1280x720 50.00 Hz 
.29.97:1280x720 29.97 Hz 
.23.98:1280x720 23.98 Hz 
.60.00:1024x768 60.00 Hz 
800x600 .60.32:800x600 60.32 Hz 
720x576.50.00:720x576 50.00 Hz 
640x480.59.94:640x480 59.94 Hz 
640x480.59.93:640x480 59.93 Hz 


Any resolution listed here can be used in the es. resolution line in /boot/batocera-boot.conf. 
For example, open the batocera-boot.conf file and add es. resolution=1280x720.59.94 to force 
ES to run at a resolution of 1280x720. 
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My EDID is not working on my Raspberry Pi specifically 


Certain Raspberry Pis seem to have a hard time parsing the display's EDID information correctly, to 
the point that it fails to even overwrite it using the above method. The Raspberry Pi can be forced to 
ignore the faulty EDID to allow Batocera to use whichever resolution it wants. 


Navigate to boot/config.txt and add the following lines: 


hdmi_ ignore edid=0xa5000080 
hdmi_group=1 


Then any HDMI mode can be used (even ones that your display won't work with, be careful!). Refer to 
Raspberry Pi's official documentation for more information. 


Display issues, when xrandr is your friend 


This section is for PC x86 and x86_64, not for SBCs like Raspberry Pi or Odroid, and mostly 
outdated as most cases should be handled with the section above. 


This tutorial is useful if you have display issues, for instance if you need to rotate your screen, or use 
a lower refresh rate. 


On Batocera v30 and lower, Batocera would simply select the highest available 
resolution + refresh rate your display reports as supported. Obviously, when running 
Batocera on weak SBCs like the Raspberry Pi connected to a 4K UHD TV, this would cause 
visual stutter as the SBC isn't powerful enough to output a 4K resolution at 60 FPS. You 
would need to force a smaller resolution (like 1920x1080) to get better performance in 


1 this scenario. 


Fortunately, from Batocera v31 and higher, Batocera will default to using the 1920x1080 
resolution as its maximum (and if you have one of those rare displays that support 120Hz 
or higher, it will default to that too for silky-smooth menu navigation! But only in 
EmulationStation, in-game will still be 60Hz by default). You can switch to using a 
genuine 4K resolution by setting your VIDEO MODE in GAME SETTINGS to 3840x2160, 
though even this won't have much a visual difference for most retro-games. 


First of all, you need to connect on your Batocera through SSH. Then run the following commands: 


export DISPLAY=:0.0 
xrandr 


This will output your display's reported “supported resolutions” (the currently used refresh rate will be 


marked with an asterisk (*) on the line of the current resolution being used). This is an example with 
an old 4/3 screen, but this is the same principle for other screens: 
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Screen 0: minimum 8 x 8, current 1366 x 768, maximum 32767 x 32767 

LVDS1 connected primary 1366x768+0+0 (normal left inverted right x axis y 
axis) 290mm x 160mm 

1366x768 60.03*+ 40.03 

1024x768 60.00 

1024x576 60.00 

960x540 60.00 

800x600 60.32 56.25 

864x486 60.00 

640x480 59.94 


If you have an error message telling you “can't open display :0.0”, you need to physically 

Y log onto your Batocera system with the display on. On a PC from EmulationStation, press 
[F1] and then launch a terminal from there (xterm from the Applications shortcut in 
the left sidebar). 


If you'd like to edit the display output, you can add your modification in a script 
/userdata/system/custom-es-config that will be automatically invoked by 
/usr/bin/emulationstation-standalone. 


You can edit the file from SSH by running the following: 


nano /userdata/system/custom-es-config 


and then saving that file to /userdata/system/custom-es-config with [Ctrl] + [0]. 


The most usual customisations are already described in /usr/bin/emuLationstation- 
standalone. If you browse the file and scroll down (using the arrow keys) to the following section: 


HHEHHHHHHHHHHHHHAERAEE 

## CUSTOMISATIONS ### 

# to customize your display, you can create the file 
/userdata/system/custom-es-config 

including this kind of commands 

rotate the screen 

xrandr -o left 

xrandr -o right 

xrandr -o inverted 


HH Gis Sis SiS 


change the resolution 
xrandr -s 640x480 


+ + 
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# change the resolution and the Hz 
# xrandr -s 640x480 -r 60 


HEHEHE AAHHHHEE AEH 
HEHHHHEHHHAEAHHAAHAA AE 


You can just copy and paste the relevant part (without the first # character that indicates it is a 
comment). For example, to just force a resolution of 640x480, create a 
/userdata/system/custom-es- config file with: 


#!/bin/bash 

# change the resolution 

xrandr -s 640x480 

To instead change the resolution to 1280x720 at 120Hz: 
#!/bin/bash 

# change the resolution and the Hz 


xrandr -s 1280x720 -r 120 


Save the file with [Ctrl] + [S] and quit with [Ctrl] + [Q]. 


cp /etc/X11/xinit/xinitrce /userdata/system/.xinitrc 


EmulationStation by default runs in full-screen, and may use the old full-screen resolution even 
through restarts, cutting off a part of its display. For testing purposes, you can temporarily use 
windowed mode for the current session with: 


exec emulationstation --windowed 
Then restart EmulationStation with the following commands to test your new resolution: 


/etc/init.d/S3lemulationstation stop 
/etc/init.d/S3lemulationstation start 


If you were to reboot Batocera at this point, you'll find that all the settings you just created have been 
lost. In order to make these settings permanent, you must save the overlay with the following 
command before rebooting: 


batocera-save-overlay 
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Q xrandr can do screen rotation; very useful for old vertical screen arcade machines! 


Hope this was easy for all. 
My TV isn't respecting that! 


Another method to manually set your output resolution is by utilizing a custom boot script. Replace 
<output> with your current output, <widthxheight> with your intended resolution and <refresh- 
rate> with your intended refresh rate in the following file and place it into 
/userdata/system/custom. sh: 


custom.sh 
#!/bin/bash 
if test -z "${DISPLAY}" 
then 
export DISPLAY=:0.0 
Jipa, 


## Manually set resolution 
xrandr --output <output> --mode <widthxheight> --rate <refresh-rate> 


For example: xrandr --output HDMI-0 --mode 1920x1080 --rate 60 


Just make sure you remember that you've done this in the future, as it will override any other settings 
you may have set via any of the above methods. 


What's the current X.Org X Server version installed? 


The current version of Xorg Batocera is using can be checked by running the following: 


head /var/log/Xorg.0.log | grep "X.Org X Server" 
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